docs(reference): use harper-config.yaml consistently in v5 - #661
Conversation
The v5 docs used both `harper-config.yaml` and the pre-v5
`harperdb-config.yaml`. Two pages contradicted each other outright:
`resources/resource-api.md` told readers to set
`authentication.enableSessions` in `harperdb-config.yaml` while
`security/jwt-authentication.md` put the sibling `authentication` token
timeouts in `harper-config.yaml`.
`harper-config.yaml` is the correct name. In HarperFast/harper,
`utility/hdbTerms.ts` labels `HDB_CONFIG_FILE` ('harperdb-config.yaml')
"Old Harper Root Config File" and `HARPER_CONFIG_FILE`
('harper-config.yaml') "Harper Root Config File". Every resolver prefers
the new name and falls back to the old one only when the new file is
absent (`config/configUtils.ts` getConfigFilePath and setConfigValue,
`bin/run.ts`, `utility/logging/harper_logger.ts`), and all writes target
the new name (`configUtils.ts` initial write, `installer.ts` boot-props
`settings_path`, and `<timestamp>-harper-config.yaml.bak` backups).
Replaces the five remaining occurrences in `reference/`, plus one in
`release-notes/v5-lincoln/v5-migration.md` that described current v5
module-loading behavior with the legacy name. `reference_versioned_docs/version-v4/`
is left alone, as is the 5.0 release note that documents the rename itself.
Also adds a note to `reference/configuration/overview.md`: with the legacy
spelling gone from every other v5 page, an instance upgraded from v4 that
still has `harperdb-config.yaml` on disk had no signal anywhere in the v5
docs. The note states the loader's actual behavior, including that
upgrading does not rename the file.
This fixes a docs-side bug that propagates into HarperFast/skills, which
generates agent-facing rules from these pages. The `checking-authentication`
rule (HarperFast/skills#81) pulled both sections into one rule, so it tells
agents to set `enableSessions` in `harperdb-config.yaml` in one step and
`operationTokenTimeout` in `harper-config.yaml` in another.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-661 This preview will update automatically when you push new commits. |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the documentation to reflect the renaming of the configuration file from harperdb-config.yaml to harper-config.yaml in Harper v5, and adds a note explaining the fallback behavior for upgraded instances. The review feedback suggests rephrasing the fallback logic explanation in reference/configuration/overview.md to improve clarity and readability.
| Harper is configured through a [YAML](https://yaml.org/) file called `harper-config.yaml` located in the Harper root directory. By default the root directory is a folder named `hdb` in the home directory of the current user. | ||
|
|
||
| :::note Instances upgraded from v4 | ||
| Before v5 this file was named `harperdb-config.yaml`, and that name is still supported. Harper looks for `harper-config.yaml` first and falls back to `harperdb-config.yaml` when only the older file is present, then writes later changes — including those made by `set_configuration` — back to whichever file it found. Upgrading does not rename the file, so an upgraded instance keeps its `harperdb-config.yaml` until you rename it. A fresh install always creates `harper-config.yaml`. |
There was a problem hiding this comment.
For improved clarity, you could rephrase the fallback logic to be more direct. The current wording is a little dense and could be simplified.
| Before v5 this file was named `harperdb-config.yaml`, and that name is still supported. Harper looks for `harper-config.yaml` first and falls back to `harperdb-config.yaml` when only the older file is present, then writes later changes — including those made by `set_configuration` — back to whichever file it found. Upgrading does not rename the file, so an upgraded instance keeps its `harperdb-config.yaml` until you rename it. A fresh install always creates `harper-config.yaml`. | |
| Before v5 this file was named harperdb-config.yaml, and that name is still supported. Harper looks for harper-config.yaml first and falls back to harperdb-config.yaml if the new file is absent. Subsequent configuration changes—including those made by set_configuration—are written back to whichever file was found. Upgrading does not rename the file, so an upgraded instance keeps its harperdb-config.yaml until you rename it. A fresh install always creates harper-config.yaml. |
kriszyp
left a comment
kriszyp
left a comment
There was a problem hiding this comment.
Looks good
🤖 Reviewed with Codex
| Harper is configured through a [YAML](https://yaml.org/) file called `harper-config.yaml` located in the Harper root directory. By default the root directory is a folder named `hdb` in the home directory of the current user. | ||
|
|
||
| :::note Instances upgraded from v4 | ||
| Before v5 this file was named `harperdb-config.yaml`, and that name is still supported. Harper looks for `harper-config.yaml` first and falls back to `harperdb-config.yaml` when only the older file is present, then writes later changes — including those made by `set_configuration` — back to whichever file it found. Upgrading does not rename the file, so an upgraded instance keeps its `harperdb-config.yaml` until you rename it. A fresh install always creates `harper-config.yaml`. |
There was a problem hiding this comment.
This overstates the resolver behavior. A normal installed node follows the exact settings_path recorded in its boot properties; the new-name-first directory lookup applies only when Harper is launched with a root-path override. Consequently, a v4-upgraded node can remain pointed at harperdb-config.yaml, and merely renaming it or creating harper-config.yaml does not update that pointer. If both files exist, startup and configuration writes can even select different files. This makes reference/mcp/migration.md:32 a concrete failure case: adding the MCP block to the newly named file may leave MCP disabled because the process still reads the legacy file. Please document how to identify/edit the active file and how to coordinate a rename with settings_path, or consolidate the resolution behavior in Harper core before promising this precedence here.
There was a problem hiding this comment.
You're right on all four points, and I confirmed each against origin/main before changing anything:
configUtils.tsgetConfigFilePathdoes the new-name-first lookup insideif (cmdArgs), wherecmdArgsisgetEnvCliRootPath()— so it only applies underROOTPATH/--ROOTPATH. With neither set it returns the literalsettings_path.installer.tswritessettings_pathonly on a fresh install; it exits early when either config file already exists, and nothing inupgrade/repoints it. So an upgraded node keeps namingharperdb-config.yaml, and renaming the file breaks startup rather than migrating it.setConfigValueresolves the file by its ownrootPathdirectory lookup that prefers the new name unconditionally, so with both files present startup and configuration writes can genuinely diverge.
I've rewritten the note around settings_path as the thing that actually selects the file and dropped the precedence claim (f050b62). It now says the active file is whatever settings_path names, that an upgraded instance usually still names harperdb-config.yaml, that upgrading neither renames the file nor repoints settings_path — so a rename has to update both — and to avoid leaving both files in the root at once.
What I have not done here is the fuller thing you asked for: a proper section on identifying and editing the active file, and coordinating a rename. I'd rather do that as a follow-up, and I think the prior question is yours: whether getConfigFilePath and setConfigValue should agree in core, since documenting the current divergence and then changing it is wasted work in both directions. Happy to write it either way once you've called that.
One scoping note on mcp/migration.md:32. That failure mode is real, but it isn't specific to this PR or to MCP — roughly 40 occurrences of harper-config.yaml already sit on pages this PR doesn't touch (configuration/options.md, security/configuration.md, http/*, models/*, operations-api/*). This PR brought 5 stragglers into line with those. MCP is just where you happened to catch it, so I'd rather not hold the consistency fix on it — but if you'd like every "set X in harper-config.yaml" instruction to point at the overview note instead of naming a filename, that's a reasonable docs-wide pass and I'll file it with the follow-up.
sent with Claude Opus 5
The note claimed Harper looks for `harper-config.yaml` first and falls back to `harperdb-config.yaml`, then writes later changes back to whichever file it found. That describes only the root-path override path. `configUtils.ts` getConfigFilePath does the new-name-first lookup inside `if (cmdArgs)`, where `cmdArgs` is `getEnvCliRootPath()` — a `ROOTPATH` environment variable or `--ROOTPATH` argument. With neither set, which is the normal installed case, it returns the literal `settings_path` from the boot properties file. `installer.ts` writes `settings_path` only on a fresh install (it exits early when either config file already exists), and nothing in `upgrade/` repoints it, so an upgraded node keeps naming `harperdb-config.yaml`. Renaming the file therefore breaks startup rather than migrating it, and because setConfigValue resolves the file by its own directory lookup that prefers the new name, leaving both files present can send startup and configuration writes to different files. Rewrites the note around `settings_path` as the thing that actually selects the file, and drops the precedence claim. Reported by @kriszyp in review. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-661 This preview will update automatically when you push new commits. |
🧹 Preview CleanupThe preview deployment for this PR has been removed. |
2 participants
Problem
The v5 docs use both
harper-config.yamland the pre-v5harperdb-config.yaml. Two pages contradicted each other about the sameauthenticationconfig section:reference/resources/resource-api.mdauthentication.enableSessionsinharperdb-config.yamlreference/security/jwt-authentication.mdauthentication.operationTokenTimeoutinharper-config.yamlThis is not cosmetic. HarperFast/skills generates agent-facing rules from these pages, and the generator is instructed to use only what the sources contain. The
checking-authenticationrule (HarperFast/skills#81) pulled both sections into one rule, so it now tells agents to setenableSessionsinharperdb-config.yamlin one step andoperationTokenTimeoutinharper-config.yamlin another. It can only be fixed here, not in the generated file.Which name is correct
harper-config.yaml. Verified againstHarperFast/harperorigin/mainrather than inferred from the docs, since both spellings appear in them:utility/hdbTerms.ts:9-11—HDB_CONFIG_FILE = 'harperdb-config.yaml'is JSDoc'd "Old Harper Root Config File";HARPER_CONFIG_FILE = 'harper-config.yaml'is "Harper Root Config File".config/configUtils.ts:387-391(getConfigFilePath),configUtils.ts:1005-1007(set_configuration),bin/run.ts:212-214,utility/logging/harper_logger.ts:461-463.configUtils.ts:286(initial write),utility/install/installer.ts:459(boot-propssettings_path), and backups are named<timestamp>-harper-config.yaml.bak(configUtils.ts:1033).The
harperdb-config.yamlstrings still scattered through the core source are legacy log/error text and comments, not the resolved filename.Changes
Five occurrences in
reference/, plus one in a v5 release note describing current behavior:reference/resources/resource-api.md—enableSessions(the one feeding the skills rule)reference/mcp/configuration.md— top-levelmcp:blockreference/mcp/migration.md— comparison table + migration stepreference/mcp/cli.md—operationsApi.network.domainSocketrelease-notes/v5-lincoln/v5-migration.md—applicationssection (v5 doc, current behavior — same bug, just outsidereference/)reference/security/jwt-authentication.mdneeded no change; it was already correct.Also: a note in the configuration overview
With the legacy spelling now gone from every other v5 page, an instance upgraded from v4 that still has
harperdb-config.yamlon disk had no signal anywhere in the v5 docs. Added a:::notetoreference/configuration/overview.mdstating the loader's actual behavior — prefers the new name, falls back, then writes later changes back to whichever file it found, and upgrading does not rename the file.This is the one intentional remaining mention of the old name in
reference/, and it is explicitly framed as legacy, so the skills generator gets a single authoritative statement instead of scattered inconsistent spellings.Deliberately left alone
reference_versioned_docs/version-v4/tree (~30 occurrences) — correct for v4, and perAGENTS.mdnot to be modified for v5 work.release-notes/v5-lincoln/5.0.md:24— that line documents the rename itself.Verification
npm run format:check— clean repo-wide.npm run build— succeeds; 406 documents processed.reference/v5/resources/resource-apiandreference/v5/security/jwt-authenticationnow contain onlyharper-config.yaml, that all three MCP pages do too, and thatreference/v4/configuration/overviewis unchanged.Follow-up for HarperFast/skills
Regenerating
checking-authenticationwill fix HarperFast/skills#81, butreference/mcp/*also feeds agent rules, so that regeneration should cover more than the auth rule.🤖 Generated with Claude Code